Almathera Ten Pack 3: CDPD 3/Almathera Ten on Ten - Disc 3: CDPD3.iso/scope/076-100/scopedisk98/automenu/readme.p

Text File | 1995-03-19 | 24.2 KB | 490 lines

Amigo : UtilityManager 1.2 © 1989 Dennis Janssen

Quick Startup Info:

  To start aum copy the included example files ".aum" and "directory2" to your
"s:" directory or assign "s:" to the directory where you placed these files.
Then change directory to the directory with "aum" in it or copy "aum" to your
"c:" directory. ( Note - you must always have the DOS command "run" in your "c:"
directory to use any DOS commands from aum. ) Now type "aum" at a cli or click on
the "WB-AUM" icon. This will open a window with gadgets also there is a menu
which can be seen by using the right mouse (menu) button.
  Aum is programmable so this is only an example setup which you can and hopefully
will modify to your own specific needs.  The documentation explains the details.

Aum 1.2 ReadMe.p

Contents
  1.Introduction - Feature Overview
     1.1.Brief Feature List
  2.***How to get Aum started***
  3.Using an included example - directory2
  4.Idiosyncrasies of aum: don't use spaces in filenames; path
  5.Purchasing Information - how to get the documentation details
     5.1.Documentation Outline
  6.Version History
  7.Regarding Version Numbering
  8.A note on the distribution of aum
  Appendix - interprocess communication for software developers

1. Introduction - Feature Overview


  Aum is a graphical, mouse operated, programmable DOS manager, or shell.  It
allows the user to easily use the elements of the Amiga's graphical interface -
windows, gadgets, menus and requesters - plus key assignments, timers, alarms
and macros to build an operating or programming environment where the main
interaction with DOS is through the mouse while retaining all the power of the
CLI.
  There are also many internal commands and features such as command
history, fast directories, variables, a mouse window manager and timed
screen blanking.
  The operating environment is built with what I call "command objects". These
can be represented graphically by menus or gadgets, or non-graphically by key
assignments, timers, alarms or macros.  The user determines a list of commands
to be associates with each command object.  When a command object is selected or
activated (eg. selecting a menu item or clicking a gadget) the command list
associated with it is sent to aum's command preprocessor and interpreter.
  The preprocessor basically expands variables and breaks up the command list
into individual commands and sends the individual commands to the command
interpreter which is in charge of executing the command. If the command is a
built in command then the command will be executed internally else the command
will be simply passed to DOS for execution as if it were typed at the CLI.
  The command objects are built with the commands _MenuItem, _MenuSubItem,
_Gadget, _StringGadget, _DisplayGadget, _Key, _Timer, _Alarm, and _Macro. These
commands will be referred to as the "command object building commands". The
gadget commands can only be used in a file and they will automatically create a
window (see the section Gadget Positioning).  The other commands can be used in
a file or as a part of other commands.
  To build the initial command objects one puts the desired command object
building commands in the file s:.aum.  Aum automatically reads that file when it
begins. You can have aum read another file when it begins by explicitly giving
it as a command line argument to the aum DOS command. Eg. aum <filename>.

1.1.Brief Feature List
    ------------------
    1.Menus : multiple switchable menu strips with optional subitems
    2.Gadgets
        2.1.Boolean Gadgets
        2.2.String Gadgets : with optional command history functions
    3."File requester" gadgets that are resizeable, can display directories,
        command history and the internal directory list.  They also have
        programmable toggle commands for each list.
    4.Fast Directories : Fast internal directory lists for practically
        instantaneous redisplaying of a directory once you've gotten that
        directory making for quick re-traversal of the directory tree of
        multiple volumes; with updating if and only if necessary.
    5.Command History : Multiple simultaneous history string gadgets are fully
        supported.  The associated command history lists can be preset,
        deleted from, displayed and operated on or executed from a display
        gadget.
    6.Multiple Windows
    7.Key assignment of command lists, 8 optional qualifiers, 256 possibilities
        per key
    8.Timers : assignment of command lists to a count down timer
    9.Alarms : assignment of command lists to specific times
   10.Macros : aliases
   11.Forty six built-in commands : including a simple debugger and a
        conditional (_if, _else), screen blanking, auto window moving and
        resizing, ipc, 46 in all.

        Alphabetical Command List:
          ? (requester command), _Abort, _ActivateStringGg, _Alarm, _BytesBlocks,
          _Cd, _CloseAllWindows, _CloseWindow, _Copy, _DebugOn, _Delete,
          _Directory, _DiskBlocksAvail, _DisplayDirectories, _DisplayGadget,
          _DisplayGlobals, _DisplayHistory, _FreeDirectory, _Gadget, _History,
          _If(_Else), _Key, _Macro, _MakeDir, _MenuDelete, _MenuItem,
          _MenuStripDelete, _MenuSubitem, _MenuSwitch, _MoveWindow, _MouseOff,
          _NewMenuStrip, _OpenWindow, _Parent, _Quit, _ReadFile, _Rename,
          _ResizeWindow, _ScreenOff, _Send, _StringGadget, _Table, _Timer, _Title,
          _ToggleAll, _Update, _Variable

   12.Variables : 3 types of string variable including one to refer to a set of
        selected files that has an implicit ("while") loop type control function
   13.Automatic Requester commands ("?") for inserting user choice points in
        command lists
   14.Interprocess Communication : Aum accepts commands from other processes
        through a separate program "send" (an executable included with the
        released files). It also can send commands to any process that is
        ready to receive its messages. Details for programmers about
        receiving aum commands is given in the Appendix.
   15.Input Handler : on/off switch for entire handler if you'd rather use a
        different one
      13.1.Programmable Mouse Accelerator : on/off and speed limit
      13.2.Window Activation : "Sun Mouse" - on/off
      13.3.Left mouse button - window to front if in a window and window is in
             any way covered by another layer, screen to front if on screen
      13.4.Left+Rignt mouse button - window to back if in a window, screen to
             back if on a screen
   16.Command preprocessor
   17.Control Table : every reasonable variable of the system is controlled by
        a control table which is in turn user controlled ; 66 variables
        including colors, sizes, special characters of preprocessor, etc.
   18.Error Codes for internal errors

2. **** How to get Aum started ****

  Aum reads an initial "startup-file" which can be set as an argument, the
default is "s:.aum". In this file the user should place lists of his/her most
used commands assigned to command objects as exemplified in the included files
and explained in the documentation. After aum is activated the user then works
in this environment activating the preset commands with the mouse through the
command objects. In most cases, you shouldn't have to type commands for DOS once
your most used commands have been preset in a "aum file". You may want to edit
an existing command for fine tuning - changing options, etc.- this can be done
in a  history gadget and again the history can be preset. You can also build
commands from displayed strings using string gadgets and the options of the
built-in _Variable command .

   **** How to get Aum started the first time ****

  To start aum copy the included files ".aum" and "directory2" to your "s:"
directory or assign "s:" to the directory where you placed these files. Then
change directory to the directory with "aum" in it or copy "aum" to your "c:"
directory. You must always have the DOS command "run" in your "c:" directory to
use any DOS commands from aum. Now type "aum" at a cli or click on the "WB-AUM"
icon. This will open a window with gadgets also there is a menu which can be
seen by using the right mouse (menu) button.

   **** How to get Aum started in general ****

  So in general to start aum from a CLI you can simply type "aum" or add as an
argument any filename you wish to use as an alternate initialization file - "aum
<filename>".
  WB-AUM, an included executable file, is necesary for Workbench startups. It is
simply a slightly modified version of the regular DOS 1.3 CLI command - it
doesn't read "s:cli-startup" but instead starts aum.

Note: Again, you must always have the DOS command "run" in your "c:" directory
to use any DOS commands from aum.

3.Using the included example files

  Included with this release are a number of files which are adapted to my
paticular pattern of computer use.  You should modify them according to your own
individual needs.  This section is a explanation so you will get an idea of some
of the uses of Aum before you get the documentation. Details of the meaning of
each command, it's arguments, options and special features are given in the
documentation obtained by mail from me as explained in the Purchasing section.
Below is a description of the function of the different gadgets in the file
"directory2".  This file is read by the aum internal command "_read
s:directory2" which is given in the startup file "s:.aum".

  This window contains two large "display gadgets" also called file requesters
or directory gadgets, three string gadgets and a number of other regular
(boolean) gadgets.  Beneath each display gadget is an associated string gadget
which is used to display information related to it's respective display gadget
such as the currently displayed directory, the number of total bytes/blocks of
the selected files, the number of free blocks on the current drive, or other
user selected values.  Below both of these string gadgets is another string
gadget that is set up to work as a "history gadget".  By hitting the up arrow
key you get a "previous" history, by hitting a down arrow you get a "next"
history. These can be and have been preset by the directory2 file. Whatever you
type there and hit return after (like a normal cli command) will be executed and
added to the history.
  Note that these functions are not "set in concrete", they have been set by the
files read at startup and all can be modified to your own special uses as
explained in the documentation.  The number of gadgets, their positions, names
and corresponding functions are set by the files. Similarly with the menus and
keys (up and down arrow keys).

  Below is a list of the "names" of the gadget - the character symbols that
appear on the gadget - and a description of the command associated with clicking
on the gadget.  This information can also be obtained by examining the files
with the help of the documentation.  Some of the gadgets are not listed since
they are easy to understand from the ones listed, eg. "Delete1".

P  gets the Parent directory of the current directory
U  Updates the current directory (any non-internal commands that changes a
     directory may require an update for accuracy)
T  Toggles all the lines in the display
b  displays the total Bytes/blocks of the selected files
d  displays the number of blocks available on the Device associated with the current
     directory; helpful if you want to know if a disk has enough room for a copy of
     the selected files
List displays the internal List of directories
Free frees an internal directory freeing the associated memory
V directory of VD0:
R directory of RAD:
0 directory of DF0:
1 directory of DF1:
r Directory of RAM:
Apd sets a variable to "-a" (append). This variable is used to control the mode
  of the _Variable command used in the gadgets "v" and "vv" so that they will
  append the contents of their associated string gadgets to the contents of the
  central string gadget. (See Documentation for the _Variable command modes)
Ins sets a variable to "-i" . This variable is used to control the mode
  of the _Variable command used in the gadgets "v" and "vv" so that they will
  insert the contents of their associated string gadgets at the cursor into the
  central string gadget. (See Documentation for the _Variable command modes)
Rep sets a variable to "-r" (replace). This variable is used to control the mode
  of the _Variable command used in the gadgets "v" and "vv" so that they will replace
  the contents of the central string gadget with the contents of their associated
  string gadgets. (See Documentation for the _Variable command modes)
Db+ switchs to Debug mode
-   switchs back from debug mode
Abt Abort the current command list
v copies the value of the string gadget to the string gadget below using the mode
    value (set above)
vv copies the value of the string gadget + the first selected file name to the
    string gadget below using the mode value (set above)
+ adds the value in the string gadget to its history list
- deletes the value of the string gadget from the history list
v sets the string gadget to the next position in the history list
^ sets the string gadget to the previous position in the history list
"Copy1 %" copies the selected files of the first list display gadget to the directory
  that is displayed in the center string gadget
"Copy1 2" copies the selected files of the first list display gadget to the directory
  that is displayed in the right upper string gadget
- resizes the gadget window to normal size
| resizes the gadget window larger
W brings the cli output window to the front
. resizes the cli output window to a point at 0 0
= resizes the cli output window brings it back to original size and position
+ resizes the cli output window adjusts to full screen size
Histry>1 displays the history list of the center string gadget and sets the "toggle
    command" (see documentation) to allow execution of any displayed command by
    simply selecting it with the left mouse button
Histry>2 displays the history list of the center string gadget and sets the "toggle
    command" (see documentation) to simply copy the command to the center
    string gadget; from there it can be edited and/or executed
1 executes the commands selected in first display gadget
"Run(1) 2" runs the commands selected in the first display gadget using as
    arguments the filenames selected in the second list display gadget

Key assignments:

F1 If an aum window is active the F1 function key is set to close the aum
windows, when hit again it reopens the windows and it will continue this cycle.
This key has no function when other program window are active.

UP DOWN  (arrow keys) The up and down arrow keys adjust the command history list
of the central string gadget when the gadget is activated by the left mouse
button.  Note: These functions are not set if the CAPS LOCK or any other
qualifier is active.

The file directory1 is a smaller version of directory2.

Please note that many features of aum do not have an example in the included files.

4.Idiosyncrasies of aum: spaces in filenames; path ; current directory;
"run" in you c:directory
  Currently aum will not handle spaces in filenames.  This means you must change
for example a volume with the name "Workbench 1.3" to something like
"Workbench1.3" or "Workbench_1.3".
  Set the paths you want (using the DOS path) before you execute aum, aum will
not know about new paths that are added after aum is started.
  To change directory you must use the internal command "_cd". The Dos command "cd"
will not be effective.
  You must always have the DOS command "run" in your "c:" directory to use any
DOS commands from aum.

5.Purchasing Information
  The full documentation with all the details and examples regarding the use of Amigo
Utility Manager is about 30 pages long and is obtained by mail. Below is an outline.

        Contents:
        1.Introduction
        2.Startup Information
        3.Commands
          3.1.Alphabetical command list
          3.2.Command names
          3.3.Command name abbreviation
          3.4.Special syntactic characters in the command format
          3.5.Internal Commands
          3.6.Commands Grouped around there related Command Objects
          3.7.Command Error Codes
        4.The Command Preprocessor
        5.Variables
        6.The Comand Interpreter
        7.The Control Tables
        8.Gadget Positioning
        9.The Mouse Handler
        10.Glossary of Special Terms
        11.Idiosyncrasies of aum: spaces in filenames; path ; "run" in you c:directory
        Appendix 1: General aum syntax
        Appendix 2: Reference Tables:
          1.Command Arguments Reference Table
          2.Control Table Reference

  Pricing for version Aum1.2 :

      DOCS:    $9.95 for the documentation (please include the version number
                     you have)
      DISK:   $14.95 for the documentation and the latest version on a disk

      SOURCE: $24.95 for the documentation, the latest version and the source
                     code in `C'.

  Updates for registered users: DOCS: $5, DISK: $10, SOURCE: $15

  Çalifornia residents add sales tax - 7%
  Outside North America add $2.00 postage and please exchange your currency for
U.S. dollars before you send.
  If you wish to use the aum interface in your product contact me regarding licensing.

Send your order to:

         Dennis Janssen
         2338 Telegraph, #237
         Berkeley,CA 94704

  Questions by interested parties and/or support for registered users is
available by phone at 415-549-2400.

  I am also available for contract programming or consulting.

  Your comments, criticisms, suggestions, etc. are most appreciated but to make
ordering by mail as simple for you as possible just a check is all you need send
if your current address is on the check. Make a note on the check of your
program version number (Aum1.2) and the code from the pricing section above
(DOCS or DISK) for the package you want.

6.Version History
  1.0a First released version
  1.01-1.04 Some bug fixes that became apparent when aum was run in different
              environments, e.g. locked hard drives
  1.05-1.06 Internal improvements
  1.07      Fixed so input handler so it will function properly when Workbench is
              loaded - this affected the function of the example F1 key
  1.08      the "-c" option with _Key doesn't work with a String Gadget because
              Intuition swallows all keys - no RAWKEY IDCMP : use "-a" instead.
              This affected the History in the center gadget
  1.1       changed the _AdjustWindow into two commands: _MoveWindow and
            _ResizeWindow, added another option to these commands
  1.11      fixed the problem with some systems having a problem it startup
            using the default filename (s:.aum); added "-n" option to
            _MenuSwitch
  1.12-1.15 fixed a bug in the _resize command; internal restructuring -
            more "object oriented"
  1.16      fixed a bug in the toggle command of 1.15; _ScreenOff now works
            with multiple screens
  1.17      fixed a problem with _closewindow; updated the example files;
            Note : internal changes require use of the new example files
            because the ordering in the command table was changed to
            alphabetical to make it easier to explain and understand- sorry
            about that
  1.18      fixed a problem with _ScreenOff for stubborn screens
  1.19      fixed _if ; improved the string gadget so it displays from the
            beginning of a string after a "too wide" value
  1.2       fixed a small bug that affected volume names. Note: no new features
            have been added in this version
  1.2.1     a few minor improvements; "_delete" now will delete the current
            directory of an empty list display gadget
  1.2.3     Fixed a bug that occured sometimes when selecting an item in a
            list display gadget.

7.Regarding Version Numbering
  Updates for the program itself will be coded as a version number increase.
When I add new features I will make a change in the first two digits (version
1.2 is an exception), corrections and improvements will be marked by changing
the third digit. An update for the readme of a particular version will be coded
as a change in the appended letter.

8.A note on the distribution of aum.
  Aum and the related files including the ReadMe but not including the
purchased documentation may be freely distributed to friends and to other
bulletin boards.

Appendix 1: For programmer's who want to there programs to receive aum
commands.
  Below in Appendix 2 is  aum's internal _Send command the final channel
through which all aum's interprocess communication messages pass.  The
external Send (included) works the same way. As you can kinda see from the
code this command takes as an argument the name of a port on the SysBase
PortList and a command string, the message - _SendMessage <port> <message>.
  To receive messages from aum here's what you do.  First you need to put
your program's named message port on the system PortList with an AddPort()
so aum can find you. Then check your port for a IntuiMessage with class set
to AUM_MESSAGE_CLASS (0x01000000), if you get one, first make a copy of the
command character string pointed to by the IntuiMessage's IAddress then
Reply() the message. That's it.  Now you can do whatever processing you
like with the message.

Example code:

#define AUM_MESSAGE_CLASS 0x01000000
  struct MsgPort CommonPort;
  CommonPort.mp_Node.ln_Name="YourNameHere";
  ...
  AddPort(&CommonPort);

  struct IntuiMessage *imessage ;
  WaitPort(&CommonPort );
  imessage=GetMsg(&CommonPort);
  class=imessage->Class;
  switch(class) {
    ...
    case AUM_MESSAGE_CLASS:
      command=TemporaryCopyOfString(imessage->IAddress);
      break;
  }
  ReplyMsg(imessage);
  ReadEvaluateCommandList (command);

  Before you exit first take your port off the PortList with RemPort() so
no other task can find you and attempt to send you a message while your
exiting. You then need to Reply() to any remaining aum messages on your
port list.

    RemPort(&CommonPort);
    while(imessage=GetMsg(&CommonPort))ReplyMsg(imessage);
    ...
    exit();

Note: because in both my internal "_SendMessage" and external "Send" command
there is a Forbid() before attempting to find the port there is no problems
regarding exit timing.
Aum is not dependent on any other response besides a Reply() but as you can
see below does Wait() for that response before getting back to other
business. Note: Aum always takes responsibility for freeing the message
memory.
  This provides a simple, effective interprocess communication mechanism. I
used the IntuiMessage because many processes use an IÐCMP in their main
input loop and since Intuition already puts those ports on the system
PortList with a generic name ("IDCMP") sometimes all you need do is rename
a Window UserPort.
  As an example, my version of Matt Dillon's DME editor has been modified
to function as described above.   Since dme (version 1.29) doesn't have
command history I map the escape key to sending aum a message to open a
borderless window with a history string gadget that mirrors the built-in
command line mode of dme.  The history gadget has its <RETURN> key command
set to send its contents to dme as a command, add the contents to its
history list and then close the window.  Each time I hit the escape key the
window with the history list is there.

Appendix 2: C Code for developers who want to be able to receive messages from
aum.

long
_SendMessage(){
  char *port_name,*message;
  long error_number;
  struct IntuiMessage *our_message;
  long message_length;
  struct MsgPort *receiver_port, *port ;

  port_name=PtrContext->c_Arguments[0];
  message=PtrContext->c_Arguments[1];
  our_message=TemporaryObject(sizeof(struct IntuiMessage)+strlen(message)+1);
  our_message->IAddress=our_message+1;
  our_message->mn_ReplyPort=port=&((struct Process*)CurrentTask)->pr_MsgPort;
  strcpy(our_message->IAddress,message);
  our_message->Class=AUM_MESSAGE_CLASS;
  Forbid();/* can't have the task try to exit while we're doing a PutMsg() */
  receiver_port=FindNameCaseInsensitive(&SysBase->PortList, port_name);
  if(receiver_port)PutMsg(receiver_port,our_message);
  Permit();
  if(receiver_port){
    WaitPort(port);
    GetMsg(port);
    return(OK);
  }
  else return(CANT_FIND_PORT);
}

Amigo : UtilityManager 1.2 © 1989 Dennis Janssen